【YUIDoc】のドキュメントを自動生成する。

前回YUIDocの出力まで試してみました。

今回はYUIDocのドキュメントをGruntで自動出力してます。

アジェンダ

• 導入準備
• gruntで自動化する
• 動作確認

導入準備

Node.jsをインストールする。

前回の記事でNode.jsをインストールしましたので、参考にインストールしてみてください。

Gruntをインストールする。

npm install -g grunt
npm install -g grunt-cli

gruntで自動化する

package.jsonの作成

今回使用したプラグイン

• grunt-contrib-watch : ファイルの更新等を自動感知して処理を実行してくれます。
• grunt-contrib-yuidoc : YUIDocを出力してくれます。

今回はyuidocsという作業フォルダを作成し、フォルダ内にpackage.jsonを準備します。

package.json

{
  "author": "Takashi Kiyota",
  "name": "YUIDocTest",
  "version": "0.9.1",
  "devDependencies": {
    "grunt": "",
    "grunt-contrib-watch" : "",
    "grunt-contrib-yuidoc"    : ""
  }
}

Nodeパッケージをインストールします。

プラグインのインストールしてみます、コンソール画面から作業ファイルまで移動し以下のコマンドを入力します。

cd C:xxx/xxx/xxxx/yuidocs
//作業フォルダまで移動、今回はyuidocsフォルダです。
npm install

正常にインストールできると、「node_modules」ファイルが作成され中にプラグインがインストールされています。

今回は監視用のjsファイルを以下に格納するようにします。(jsファイルの格納先は各自で設定できます。)

[作業ファイル/assets/js/]

Gruntfile.jsの作成

Gruntの設定ファイルを作業フォルダのトップ階層に作成します。

Gruntfile.js

module.exports = function (grunt) {
 
    'use strict';
 
    [
        'grunt-contrib-yuidoc',
        'grunt-contrib-watch'
    ].forEach(function (name) {
            if (!/template/.test(name)) {
                grunt.loadNpmTasks(name);
            }
        });
 
    grunt.initConfig({
 
        watch: {
            yuidoc: {
                //監視ファイルの指定
                files: ['assets/js/**/*.js'],
                tasks: ['yuidoc']
            }
        },
  
        yuidoc: {
            dist: {
                'name': 'プロジェクト名',
                'description': "プロジェクトの概要",
                'version': 'バージョン指定',
                options: {
                    //出力パスの指定(今回はGruntfile.jsと同階層に出力するよう指定)
                    paths: './',
                    //YUIDocファイルを出力するディレクトリ名を記述
                    outdir: 'yuidocs/'
                }
            }
        },
 
    });
 
    grunt.registerTask('default', ['watch']);
    grunt.registerTask('build', ['yuidoc']);
};

動作確認

それでは動作を確認したいと思います。

Gruntfile.jsで設定した監視フォルダ内にjsファイルを作成します。

[作業ファイル/assets/js/example.js]

/**
* MyClassの説明
*
* @class MyClass
* @constructor
*/
function MyClass() {
 
    /**
    * hogeメソッドです。
    *
    * @method hoge
    * @param {String} name
    * @param {Int} age 
    */
 
    this.hoge = function(name , age){
 
        //処理を記述
 
    }
 
    /**
    * fugaプロパティです。
    * 
    * @property fuga
    * @type Int
    * @default 10
    */
 
    this.fuga  =  10;
 
}

コンソール画面からgurnt起動をさせます。

cd C:xxx/xxx/xxxx/yuidocs
//作業フォルダまで移動、今回はyuidocsフォルダです。
grunt

起動後、jsフォルダ内のjsファイルを編集するとGruntで設定していたタスクが走ってくれます。

作業ディレクトリのトップ階層にyuidocsというファイル内にドキュメントが作成できました。 中身のファイルを確認すると、YUIDoc用のドキュメントが生成されていました。

まとめ

YUIDocの自動出力の一連の流れをご紹介しました。これで都度都度、出力コマンドを叩かずにドキュメントを出力できるようになりました。
めんどくさがらず、コード内にコメントを記述して、メンテナンスを高めていきましょう！(戒めに自分に言い聞かせてます。)